Aminet 28/Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso/Aminet/util/libs/MMULib.lha/MMULib/Autodocs/memory.doc

Text File | 1998-09-27 | 14.5 KB | 489 lines

TABLE OF CONTENTS

memory.library/--Background--
memory.library/CreateAdrSpace
memory.library/DeleteAdrSpace
memory.library/AllocVMemPool
memory.library/DeleteVMemPool
memory.library/AttachTask
memory.library/DetachTask
memory.library/AllocVMVec
memory.library/FreeVMVec
memory.library/LockVMVec
memory.library/UnlockVMVec
memory.library/--Background--                    memory.library/--Background--

    PURPOSE
        The memory.library provides functions for memory allocation and
        deallocation that are superior to those of the exec.library.

        The functions of this library will provide so called "virtual memory"
        by using the mmu.library, memory that can be swapped to disk
        transparently to the application. Hence, applications will be usually
        able to allocate more memory than physically available.

        Certain access restrictions arise for memory allocated by the
        memory.library. First, you can't access it in Forbid() or Disable()
        state. Second, it can't be shared amongst different pools. You
        must explicitly attach the tasks that should be able to access memory
        from a given pool. Thus, you can't use this kind of memory for keeping
        Os structures since they may be passed to different tasks for further
        processing. Third, you MAY NOT access virtual memory in a situation
        where file I/O would be impossible. That is, DO NOT access this mem
        while:
            - holding a lock on the dos.library handler lists
            - disabling the filing system of the swap partition
            - making the swapping exec.device unaccessible
            - taking over the hardware
        The mmu.library will try to detect such situations and will throw
        a guru if that's possible. However, if it is not, these situations
        will result in a dead-lock! Keep care!


        This restriction can be somewhat weakened by the LockVMVec/UnlockVMVec
        functions. By calling these functions, you can lock a given memory
        vector in memory and hence, will be able access it WITHIN Forbid().
        It returns a pointer to the physical location of that memory block
        which must be used if that memory is passed to a different task or
        other hardware components.

        This kind of "virtual memory" is of course some kind of a
        "poor man's solution" for implementing virtual memory. No exec
        function will be patched and old programs will continue to work
        without any change. The library is of course of limited or no use
        at all for old programs since it doesn't redirect standard memory
        allocation functions to their "virtual" counterparts. Thus, this
        is a very "conservative" approach to overcome this limitation of
        AmigaOs.

        A special "VMM/GigaMem" patch might be made available that uses
        the functions of this library to provide virtual memory to every
        task. However, since this CAN'T be fully compatible to old programs
        and may, therefore, cause some compatibility problems. It should be
        up to the user if she/he likes to install a patch like this or not,
        but it should NOT the way how virtual memory enters AmigaOs, at
        least not now.

        The basic objects the memory.library handles is first the
        "AddressSpace" object. It defines - as it says - an common
        address space for the tasks attachted to it. It is the memory.library
        implementation of the mmu.library "context". Each address space can
        be linked to as many tasks as you wish, but a task can be attached
        to only one address space at a time.
        The actual memory allocation is done from "VMPools". They are the
        memory.library counterpart of the exec "memory pools". Each address
        space may contain as many "VMPools" as you wish, but only tasks
        attachted to the address space of the pool can use it.
memory.library/CreateAdrSpace                    memory.library/CreateAdrSpace

    NAME
        CreateAdrSpace    -    create a new address space.

    SYNOPSIS
        BOOL CreateAdrSpace( );
        d0

        BOOL CreateAdrSpace( VOID );

    FUNCTION
        Build a new address space and attach the calling task to this
        address space.

    INPUTS
        none.

    RETURNS
        a true/false boolean success indicator.

    NOTES
        This call will build a new mmu.library "Context" for the calling
        task and will enter this context for this task. The task calling
        this function should not be attachted to any other address space
        or this task will fail. A task can be attached to one address
        space at a time only.

        This call will change the tc_Switch() and tc_Launch() function
        pointers of the calling task.

    SEE ALSO
        DeleteAdrSpace(), exec/tasks.h

memory.library/DeleteAdrSpace                    memory.library/DeleteAdrSpace

    NAME
        DeleteAdrSpace    -    delete an address space.

    SYNOPSIS
        DeleteAdrSpace( );

        DeleteAdrSpace( void );

    FUNCTION
        This call deletes the address space of the calling task. It will
        leave the private context build for this address space and will
        enter the global context.

    INPUTS
        none.

    RETURNS
        nothing.

    NOTES
        This call uses the CurrentContext() call of the mmu.library and
        deletes this context. The task is then re-attachted to the global
        common context. No virtual memory must be used at that time, nor
        any other task may be attachted to this address space.

        It is safe to call this function if the calling task isn't attached
        to any address space. Nothing will happen in this case.

    SEE ALSO
        CreateAdrSpace(), mmu.library/CurrentContext()

memory.library/AllocVMPool                            memory.library/AllocVMPool

    NAME
        AllocVMPool    -    create a pool of virtual memory.

    SYNOPSIS
        pool = AllocVMPool( reqments, attributes );
        d0                    d0          d1

        VMPool * AllocVMPool( ULONG, ULONG );

    FUNCTION
        Creates a memory pool for virtual memory and adds the calling task
        to the list of tasks that can safely use this pool.

    INPUTS
        reqments    -    an exec style memory attributes flags field.
                This defines the memory type the pool will be taken from,
                not ANY implications about the logical addresses asssigned
                to the memory allocated from that pool. Thus, if you call
                LockVMVec() later on, that vector will be mapped to the
                memory described by the reqments above.

                The following bits, defined in exec/memory.h will be
                ignored:

                MEMF_PUBLIC        -    as the pool is always private in
                    this sense.

                MEMF_CLEAR        -    as this flag must be specified
                    individually when allocating memory from the pool.

        attributes    -    special attribute flags.

                VMEMF_PRIVATE    -    make the memory in the pool invalid
                    to other tasks.

                VMEMF_PROTECT    -    protect the underlying MMU context.

                VMEMF_NONCACHE    -    mark the memory in the pool
                    explicitly as noncacheable
                    (defaults to the cache type of the physical memory)

                VMEMF_PRECISE    -    mark the memory in the pool as
                    requiring the precise exception model.
                    (only for special MMUs, not available in general)
                    Implies VMEMF_NONCACHE

                VMEMF_SERIALIZED-    mark the memory as serialized non-
                    cacheable.
                    (only for special MMUs, not available in general).

        RETURNS
            A handle to the pool or NULL in case of failure. The calling
            task will be prepared to use the memory in the pool.

        NOTES
            To use this call, a private address context must have been
            build before.

        SEE ALSO
            CreateAdrSpace(), DeleteVMPool(), exec/memory.h

memory.library/DeleteVMPool                        memory.library/DeleteVMPool

    NAME
        DeleteVMPool    -    Delete a virtual memory pool.

    SYNOPSIS
        result    =    DeleteVMPool( pool);
        d0                          a0

        BOOL DeleteVMPool (VMPool *);

    FUNCTION
        Deletes the given virtual memory pool in question, releases the
        memory occupied by the pool and the release the used space on disk.

    INPUTS
        pool    -    a handle to a VMPool as created by AllocVMPool.
            Passing in NULL is safe.

    RESULTS
        A boolean that indicates whether some memory in the pool is
        still allocated. Can be usually ignored but is useful for
        debugging.

    NOTES

    SEE ALSO
        AllocVMPool()

memory.library/AttachTask                            memory.library/AttachTask

    NAME
        AttachTask - attach a task to the address space of the calling task.


    SYNOPSIS
        result = AttachTask( task);
        d0                     a1

        BOOL AttachTask(struct Task *);

    FUNCTION
        To allow another task sharing the same address space than the calling
        task, this new task must be attached to the common address space
        with this call. Afterwards, the task passed in the parameter may
        use the same virtual memory pools as the calling task.

    INPUTS
        task    -    The task to be added to the allowed tasks for the
            address space of the calling task.

    RETURNS
        a boolean indicating whether it was possible to add the task to
        the adrspc.

    NOTES
        It is intentionally not possible to add tasks to an address space
        of a different task than the calling one.

    SEE ALSO
        DetachTask()

memory.library/DetachTask                            memory.library/DetachTask

    NAME
        DetachTask - remove the calling task from its address space.

    SYNOPSIS
        DetachTask( );

        VOID DetachTask( VOID );

    FUNCTION
        Remove the calling task from its address space and let it enter
        the common context again. The address space itself will continue
        to exist.

    INPUTS
        none.

    RETURNS
        nothing.

    NOTES
        The current task is, after calling this function, no longer allowed
        to use any virtual memory allocated by the memory.library pool
        functions of that pool.

        The only use of this function is to pass an address space from a
        creator task to its children, i.e. by first calling CreateAdrSpace,
        then launching the child process, attaching the child process to
        that address space and removing the creator task from that pool.
        It's then up to the children to remove themselves from that address
        space on exit and to delete the address space created this way.

        It is safe to call this function if the current task isn't attached
        to any address space. Nothing will happen in this case.

    SEE ALSO
        AttachTask(), CreateAdrSpace()

memory.library/AllocVMVec                            memory.library/AllocVMVec

    NAME
        AllocVMVec    -    allocate virtual memory from a pool.

    SYNOPSIS
        mem = AllocVMVec( pool, bytesize, flags);
        d0                  a0    d0          d1

        void * AllocVMVec( Pool *, ULONG, ULONG);

    FUNCTION
        This function allocates memory from a given virtual pool.

    INPUTS
        pool    -    The pool to allocate the memory from.

        bytesize-    The size of the memory required. This might be larger
            than the amount of physical memory available, but you won't
            be able to access the complete memory block at once or
            to lock it in memory.

        flags    -    allocation flags. The following flags are used:

            MEMF_PUBLIC        The returned memory will be public, i.e.
                            non-virtual.

            MEMF_REVERSE    The memory will be allocated from the pool
                            in reverse order.

            MEMF_CLEAR        The memory will be wiped out before it is
                            passed back.

            All other memory relevant flags as the caching mode and whether
            the memory is in CHIP or in FAST memory is determined by the
            flags used when allocating the pool.

    RETURNS
        the memory block allocated or NULL for failure. If the calling
        task is a process, the pr_Result2 field will be set to
        ERROR_NO_FREE_STORE (103).

    NOTES
        This call may break a Forbid() state. It may swap out pages of
        virtual memory if necessary.

        The returned memory will be aligned to at least one longword,
        the size might be rounded somewhat, but will at least contain
        the number of bytes specified by the argument.

        To be able to allocate memory from the pool, the calling task
        must have been the creator of that pool or must have been added
        to the list of allowed tasks for that pool with AttachTask().

    SEE ALSO
        FreeVMVec(), AttachTask(), exec/memory.h

memory.library/FreeVMVec                            memory.library/FreeVMVec

    NAME
        FreeVMVec    -    allocate virtual memory from a pool.

    SYNOPSIS
        FreeVMVec( pool, mem);
                   a0    a1

        VOID FreeVMVec( Pool *, void *);
                        a0        a1

    FUNCTION
        This function returns memory allocated from the pool.

    INPUTS
        pool    -    The pool the memory was taken from.

        mem        -    The memory vector to free. No byte size is passed,
                the size is implicit. It is safe to pass NULL here. No
                action is performed in this case.

    RETURNS
        none.

    NOTES
        This call may break a Forbid() state. It may swap in pages of
        virtual memory if necessary.

        To be able to call this function, the calling task must either
        the creator of the pool, or any other task that has been attached
        to the pool with AttachTask().

    SEE ALSO
        AllocVMVec(), AttachTask()
memory.library/LockVMVec                            memory.library/LockVMVec

    NAME
        LockVMVec    -    Lock a memory vector in memory.

    SYNOPSIS
        phmem = LockVMVec( pool, mem);
        d0                    a0      a1

        void * LockVMVec( Pool *, void *);

    FUNCTION
        This function locks the specified vector in memory such that it
        is guaranteed to be non-virtual and accessable by all tasks and
        to all Os functions. The physical address of that memory is
        returned as it should be used to "the outher world".

    INPUTS
        pool    -    a handle to the memory pool the memory was taken from.

        mem        -    the pointer to the memory vector in question. This is
            the logical address returned by AllocVMVec, not a physical
            address.

    RETURNS
        a pointer to the location of that memory block in physical memory
        or NULL if not enough physical memory is available to swap in that
        page in question.

    NOTES
        The calling task must be either the task that created the pool,
        or any other task that was attachted to that pool.

        Using this call turns effectively private virtual memory in
        standard exec memory. Therefore, not too many virtual pages should
        be locked and this call should be avoided in general unless you
        need to swap in the virtual memory in question TEMPORARILY. Call
        UnlockVMVec() as soon as possible to allow swapping out of the
        memory again.

        Due to the memory paging of the MMU, this call swaps actually more
        than the desired memory block in.

        This call may break a forbid state, it MAY fail if not enough
        physical memory is available.

        This call nests - each call to LockVMVec() must be matched by one
        call to UnlockVMVec().

    SEE ALSO
        UnlockVMVec()

memory.library/UnlockVMVec                            memory.library/UnlockVMVec

    NAME
        UnlockVMVec    -    Lock a memory vector in memory.

    SYNOPSIS
        UnlockVMVec( pool, mem);
                     a0       a1

        VOID UnlockVMVec( Pool *, void *);

    FUNCTION
        This function unlocks a memory block and re-allows swapping out
        of that memory block.

    INPUTS
        pool    -    a handle to the memory pool the memory was taken from.

        mem        -    the pointer to the memory vector in question, the
            logical address.

    RETURNS
        nothing.

    NOTES
        The calling task must be either the task that created the pool,
        or any other task that was attachted to that pool.

        This call turns locked memory again in virtual memory and allows
        the library to swap it out again.

        DO NOT use the physical address returned by LockVMMem() again
        after having called this function.

    SEE ALSO
        LockVMVec()